Graphics Plus

home *** CD-ROM | disk | FTP | other *** search

/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / source.lha / Geomview / doc / geomview-2 < prev next >

Wrap

Text File | 1993-12-06 | 49.6 KB | 1,489 lines

Info file: geomview, -*-Text-*- produced by texinfo-format-buffer from file: geomview.tex File: geomview Node: Cameras, Prev: Lighting Panel, Up: Interaction, Next: Saving Cameras ======= A camera in Geomview is the object that corresponds to a camera window. By default there is only one camera, but it is possible to have as many as you want. You can control certain aspects of the way the world is drawn in each camera window via the *Cameras* panel. If the target object is a camera, the *Cameras* panel affects that camera. If the target object is not a camera, the *Cameras* panel affects the "current camera". The current camera is the camera of the window that the mouse cursor is in, or was in most recently if the cursor is not in a camera window. Thus, if you use the keyboard shortcuts for the actions in the *Cameras* panel while the cursor is in a camera window, the actions apply to that camera, unless you have explicitly selected another camera. *Add Camera* Clicking on this button causes Geomview to create a new camera. The new camera's window appears, and an entry for it appears in the *TARGET* browser of the *Main* panel. *Software Shading* This button controls whether Geomview does shading calculations in software. The default is to let the hardware handle them, and in Euclidean space this is almost certainly best because it is faster. In hyperbolic and spherical space, however, the shading calculations that the hardware does are incorrect. Click this button to turn on correct but slower software shading. *Background Color* This button brings up a color chooser which you can use to set the background color of the camera's window. *PROJECTION* This browser lets you pick between perspective and orthogonal projection for this camera. *Near clip* This determines the distance in world coordinates of the near clipping plane from the eye point. It must be a positive number. *Far clip* This determines the distance in world coordinates of the far clipping plane from the eye point. It must be a positive number and in general should be larger than the *Near clip* value. *FOV* This is the camera's field of view, measured in its shorter direction. In perspective mode, it is an angle in degrees. In orthographic mode, it is the linear size of the field of view. This number can be modified with the mouse in *Cam Zoom* mode. *Focal Length* The focal length is intended to suggest the distance from the camera to an imaginary plane of interest. Its value is used when switching between orthographic and perspective views (and during stereo viewing), so as to preserve apparent size of objects lying at the focal distance from the camera. *Lines Closer* This number has to do with the way lines are drawn. Normally Geomview's z-buffering algorithm can get confused when drawing lines that lie exactly on surfaces (such as the edges of an object); due to machine round-off error, sometimes the lines appear to be in front of the surface and sometimes they appear behind it. The *Lines Closer* value is a fudge factor --- Geomview nudges all the lines that it draws closer to the camera by this amount. The number should be a small integer; try 5 or 10. 0 turns this feature off completely. Choosing too large a value will make lines visible even though they should be hidden. *SPACE MODEL* This determines the model used to draw the world. It is most useful in hyperbolic and spherical spaces. You probably don't need to touch this browser if you stay in Euclidean space. For more information about these models, *Note Non-Euclidean Geometry::. *Virtual* This is the default model and represents the natural view from inside the space. *Projective* The projective model of hyperbolic and spherical space. Geoms move under isometries of the space, and cameras move by Euclidean motions. By default in the projective model, the Euclidean unit sphere is drawn. In hyperbolic space this is the sphere at infinity. In Euclidean space the projective model is the same as the virtual model except that the sphere is drawn by default. *Conformal* The conformal model of hyperbolic and spherical space. Geoms move under isometries of the space, and cameras move by Euclidean motions. In Euclidean space, the conformal model amounts to inverting everything in the unit sphere. *Draw Sphere* This controls whether Geomview draws the unit sphere. By default the unit sphere appears in the projective and conformal models. In hyperbolic space this is the sphere at infinity. In spherical space it is the equatorial sphere. *Done* This button dismisses the *Cameras* panel. File: geomview Node: Saving, Prev: Cameras, Up: Interaction, Next: Command Obscure Saving your work ================ Geomview's *Save* panel lets you store Geomview objects and other information in files that you can read back into Geomview or other programs. To use the *Save* panel you select the desired format in the browser next to the word *Save*, enter the name of the object you want to save in the text field next to the word *for*, and enter the name of the file you wish to save to in the long text field next to the word *in*. You can then either hit `RET' or click on the *OK* button. When the file has been written, the *Save* panel disappears. If you want to dismiss the *Save* panel without writing a file, click the *Cancel* button. If you specify `-' as the file name, Geomview will write the file to standard output, i.e. in the shell window from which you invoked Geomview. The possible formats are given below. The kind of object that can be written with each format is given in parentheses. *Commands (any object)* This write a file of gcl commands containing all information about the object. Loading this file later will restore the object as well as all other information about it, such as appearance, transformations, etc. *Geometry alone (geom)* This writes an OOGL file containing just the geometry of the object. *Geometry [in world] (geom)* This writes an OOGL file containing just the geometry of the object, transformed under Geomview's current transformation for this object. Use this if you have moved the object from its initial position and want to save the new position relative to the world. *Geometry [in universe] (geom)* This writes an OOGL file containing just the geometry of the geom, transformed under both the object's transformaton and the world's transformation. *RMan [->tiff] (camera)* Writes a RenderMan file which when rendered creates a tiff image. *RMan [->frame] (camera)* Writes a RenderMan file which when rendered causes an image to appear in an Iris window. *SGI snapshot (camera)* Write an SGI raster file. A bell rings when the snapshot is complete. *Camera (camera)* Writes an OOGL file of a camera. *Transform [to world] (any object)* Writes an OOGL transform file giving Geomview's transform for the object. *Transform [to universe] (any object)* Writes an OOGL transform file giving a transform which is the composition of Geomview's transform for the object and the transform for the world. *Window (camera)* Writes an OOGL window file for a camera. *Panels* Writes a gcl file containing commands which record the state of all the Geomview panels. Loading this file later will restore the positions of all the panels. File: geomview Node: Command Obscure, Prev: Saving, Up: Interaction, Next: Keyboard Shortcuts The Commands and Obscure Panels =============================== The *Commands* panel lets you type in a gcl command. When you hit `RET', Geomview interprets the command and prints any resulting output or error messages on standard output. You can edit the text and hit `RET' as many times as you like, in general, whenever you hit `RET' with the cursor in the *Commands* panel, Geomview tries to interpret whatever text you have typed in the text field as a command. The *Obscure* panel is for relatively obscure things that don't really belong on any of the other panels. In the present version of Geomview, the *Obscure* panel includes the *NORMALIZE GEOMETRY* browser, which controls the kind of geometry normalization that Geomview does, and several buttons affecting motion style. Normalization is a kind of scaling; Geomview can scale an object so that it fits within a certain region. The main point of normalization is to allow you to easily view all of an object without having to worry about how big it is. We are gradually replacing Geomview's normalization feature with more robust camera positioning features. In general, the best way to make sure you are seeing all of an object is to use the *Look At* button on the *Tools* panel. Normalization may be completely replaced by this and other features in a future version of Geomview. Normalization is a property that applies to each geom separately. The *NORMALIZE GEOMETRY* browser affects the normalization property of target geom. If the target geom is "World", it affects all geoms. *None* Do no normalization. *Individual* Normalize this geom to fit within a unit sphere. *Sequence* This resembles "Individual", except when an object is changing. Then, "Individual" tightly fits the bounding box around the object whenever it changes and normalizes accordingly, while "Sequence" normalizes the union of all variants of the object and normalizes accordingly. *Keep* This leaves the current normalization transform unchanged when the object changes. It may be useful to apply "Individual" or "Sequence" normalization to the first version of a changing object to bring it in view, then switch to "Keep". The *Motion Style* controls include the following buttons. *[ui] Inertia* Normally, moving objects have inertia: if the mouse is still moving when the button is released, the selected object continues to move. When *Inertia* is off, objects cease to move as soon as you release the mouse. *[uc] Constrain Motion* It's sometimes handy to move an object in a direction aligned with a coordinate axis: exactly horizontally or vertically. Selecting *Constrain Motion* changes the interpretation of mouse motions to allow this; approximately-horizontal or approximately-vertical mouse dragging becomes exactly horizontal or vertical motion. Note that the motion is still along the X or Y axes of the camera in which you move the mouse, not necessarily the object's own coordinate system. *[uo] Own Coordinates* It's sometimes handy to move objects with respect to the coordinate system where they were defined, rather than with respect to some camera. While *Own Coordinates* is selected, all motions are interpreted that way: dragging the mouse rightward in translate mode moves the object in its own +X direction, and so on. May be especially useful in conjunction with the *Constrain Motion* button. File: geomview Node: Keyboard Shortcuts, Prev: Command Obscure, Up: Interaction, Next: OOGL File Formats Keyboard Shortcuts ================== Most actions that you can do through Geomview's panels have equivalent keyboard shortcuts so that you can do the same action by typing a sequence of keys on the keyboard. This is useful for advanced users who are familiar with Geomview's capabilities and want to work quickly without having to have lots of panels cluttering up the screen. Keyboard shortcuts usually are indicated in square brackets ([ ]) near the corresponding item in a panel. For example, the keyboard shortcut for *Rotate* mode is 'r'; this is indicated by "[r]" appearing before the word "Rotate" in the *MOTION MODE* browser. To use this keyboard shortcut just hit the `r' key while the mouse cursor is in any Geomview window. Do not hit the `RET' key afterwards. Some keyboard shortcuts consist of more than one key. In these cases just type the keys one after the other, with no `RET' afterwards. Keyboard shortcuts are case sensitive. You can cancel a multi-key keyboard shortcut that you have started by typing any invalid key, for example `^'. Keyboard commands apply while the cursor is in any camera window and most control panels. Many keyboard shortcuts allow numeric arguments which you type as a prefix to the command key(s). For example, the shortcut for *Near clip* in the camera panel is `v n'. To set the near clip plane to "0.5", type `0.5 v n'. Commands that don't take a numeric prefix toggle or reset the current value. Most commands allow one of the following selection prefixes. If none is provided the command applies to the target object. `g' world geom `g#' #'th geom `g*' All geoms `c' current camera `c#' #'th camera `c*' All cameras For example, `g 4 a f' means toggle the face drawing of object *g4*. The text field in the upper left corner of the *Main* panel shows the state of the current keyboard shortcut. In addition to the keyboard shortcuts for the panel commands, there is also a shortcut for picking a target object: type the short name of the object followed by `p'. For example, to select object *g3*, type `g 3 p'. This only works with the short names --- the ones that appear in square brackets ([ ]) in the *TARGET* browser of the *Main* panel. Below is a summary of all keyboard shortcuts. Draw `af' Faces `ae' Edges `an' Normals `ab' Bounding Boxes `aV' Vectors Shading `0as' Constant `1as' Flat `2as' Smooth `3as' Smooth, non-lighted `aT' allow transparency Other `av' eVert normals: always face viewer `#aw' Line Width (pixels) `#ac' edges Closer than faces (try 5-100) Color `Cf' faces `Ce' edges `Cn' normals `Cb' bounding boxes `CB' background Motions `r' rotate `t' translate `z' zoom FOV `f' fly `o' orbit `s' scale `w' recenter target `W' recenter all `h' halt `H' halt all `@' select center of motion (e.g. `g 3 @') `L' Look At object Viewing `0vp' Orthographic view `1vp' Perspective view `vd' Draw other views' cameras `#vv' field of View `#vn' near clip distance `#vf' far clip distance `v+' add new camera `vx' cursor on/off `vb' backfacing poly cull on/off `#vl' focal length `v~' Software shading on/off Panels `Pm' Main `Pa' Appearance `Pl' Lighting `Po' Obscure `Pt' Tools `Pc' Cameras `PC' Commands `Pf' Files `Ps' Save `P-' read commands from tty Lights `ls' show lights `le' edit lights Space `me' Euclidean `mh' Hyperbolic `ms' Spherical Model `mv' Virtual `mp' Projective `mc' Conformal Other `0N' normalizaton: none `1N' normalization: each `2N all' normalization: all `ui' motion: Inertia `uc' motion: Constrain to axis `uo' motion: object's Own coordinates `<' `Pf' load geometry/command file `dd' delete target object `>' `Ps' save state to file `TV' NTSC mode toggle `p' pick as target object (e.g. `g 3 p') With no prefix, selects the object under the mouse cursor (like double-clicking the right mouse) File: geomview Node: OOGL File Formats, Prev: Keyboard Shortcuts, Up: Top, Next: Conventions OOGL File Formats ***************** The objects that you can load into Geomview are called OOGL objects. OOGL stands for "Object Oriented Graphics Library"; it is the library upon which Geomview is built. There are many different kinds of OOGL objects. This chapter gives syntactic descriptions of file formats for OOGL objects. Examples of most file types live in Geomview's `data/geom' directory. * Menu: * Conventions:: Conventions. * Object File Formats:: Object File Formats. * Non-geometric objects:: Non-geometric objects. File: geomview Node: Conventions, Prev: OOGL File Formats, Up: OOGL File Formats, Next: Common syntax Conventions =========== * Menu: * Common syntax:: Syntax Common to All OOGL File Formats. * File names:: File Names. * Vertices:: Vertices. * Surface normal directions:: Surface normal directions. * Transformation matrices:: Transformation matrices. * Binary format:: Binary format. * References:: Embedded objects and external-object references. * Appearances:: Appearances. File: geomview Node: Common syntax, Prev: Conventions, Up: Conventions, Next: File names Syntax Common to All OOGL File Formats -------------------------------------- Most OOGL object file formats are free-format ASCII --- any amount of white space (blanks, tabs, newlines) may appear between tokens (numbers, key words, etc.). Line breaks are almost always insignificant, with a couple of exceptions as noted. Comments begin with # and continue to the end of the line; they're allowed anywhere a newline is. Binary formats are also defined for several objects; *Note Binary format::, and the individual object descriptions. Typical OOGL objects begin with a key word designating object type, possibly with modifiers indicating presence of color information etc. In some formats the key word is optional, for compatibility with file formats defined elsewhere. Object type is then determined by guessing from the file suffix (if any) or from the data itself. Key words are case sensitive. Some have optional prefix letters indicating presence of color or other data; in this case the order of prefixes is significant, e.g. `CNMESH' is meaningful but `NCMESH' is invalid. File: geomview Node: File names, Prev: Common syntax, Up: Conventions, Next: Vertices File Names ---------- When OOGL objects are read from disk files, the OOGL library uses the file suffix to guess at the file type. If the suffix is unrecognized, or if no suffix is available (e.g. for an object being read from a pipe, or embedded in another OOGL object), all known types of objects are tried in turn until one accepts the data as valid. File: geomview Node: Vertices, Prev: File names, Up: Conventions, Next: Surface normal directions Vertices -------- Several objects share a common style of representing vertices with optional per-vertex surface-normal and color. All vertices within an object have the same format, specified by the header key word. All data for a vertex is grouped together (as opposed to e.g. giving coordinates for all vertices, then colors for all vertices, and so on). The syntax is `X Y Z' (3-D floating-point vertex coordinates) or `X Y Z W' (4-D floating-point vertex coordinates) optionally followed by `NX NY NZ' (normalized 3-D surface-normal if present) optionally followed by `R G B A' (4-component floating-point color if present, each component in range 0..1. The A (alpha) component represents opacity: 0 transparent, 1 opaque.) Values are separated by white space, and line breaks are immaterial. File: geomview Node: Surface normal directions, Prev: Vertices, Up: Conventions, Next: Transformation matrices Surface normal directions ------------------------- Geomview uses normal vectors to determine how an object is shaded. The direction of the normal is significant in this calculation. When normals are supplied with an object, the direction of the normal is determined by the data given. When normals are not supplied with the object, Geomview computes normal vectors automatically; in this case normals point toward the side from which the vertices appear in counterclockwise order. On parametric surfaces (Bezier patches), the normal at point P(u,v) is in the direction dP/du cross dP/dv. File: geomview Node: Transformation matrices, Prev: Surface normal directions, Up: Conventions, Next: Binary format Transformation matrices ----------------------- Some objects incorporate 4x4 real matrices for homogeneous object transformations. These matrices act by multiplication on the right of vectors. Thus, if p is a 4-element row vector representing homogeneous coordinates of a point in the OOGL object, and A is the 4x4 matrix, then the transformed point is p' = p A. This matrix convention is common in computer graphics; it's the transpose of that often used in mathematics, where points are column vectors multiplied on the right of matrices. Thus for Euclidean transformations, the translation components appear in the fourth row (last four elements) of A. A's last column (4th, 8th, 12th and 16th elements) are typically 0, 0, 0, and 1 respectively. File: geomview Node: Binary format, Prev: Transformation matrices, Up: Conventions, Next: References Binary format ------------- Many OOGL objects accept binary as well as ASCII file formats. These files begin with the usual ASCII token (e.g. `CQUAD') followed by the word `BINARY'. Binary data begins at the byte following the first newline after `BINARY'. White space and a single comment may intervene, e.g. OFF BINARY # binary-format "OFF" data follows Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both in big-endian format (i.e., with most significant byte first). This is the native format for 'int's and 'float's on Sun-3's, Sun-4's, and Irises, among others. Binary data formats resemble the corresponding ASCII formats, with ints and floats in just the places you'd expect. There are some exceptions though, specifically in the `QUAD' and `OFF' file formats. Details are given in the individual file format descriptions. *Note QUAD::, and *Note OFF::. Binary OOGL objects may be freely mixed in ASCII object streams: LIST { = MESH BINARY ... binary data for mesh here ... } { = QUAD 1 0 0 0 0 1 0 1 0 0 1 0 } Note that ASCII data resumes immediately following the last byte of binary data. Naturally, it's impossible to embed comments inside a binary-format OOGL object, though comments may appear in the header before the beginning of binary data. File: geomview Node: References, Prev: Binary format, Up: Conventions, Next: Appearances Embedded objects and external-object references ----------------------------------------------- Some object types (`LIST', `INST') allow references to other OOGL objects, which may appear literally in the data stream, be loaded from named disk files, or be communicated from elsewhere via named objects. Gcl commands also accept geometry in these forms. The general syntax is <oogl-object> ::= [ "{" ] [ "define" `symbolname' ] [ "appearance" `appearance' ] [ ["="] `object-keyword' ... | "<" `filename' | ":" `symbolname' ] [ "}" ] where "quoted" items are literal strings (which appear without the quotes), [bracketed] items are optional, and | denotes alternatives. Curly braces, when present, must match; the outermost set of curly braces is generally required when the object is in a larger context, e.g. when it is part of a larger object or embedded in a Geomview command stream. For example, each of the following three lines: { define fred QUAD 1 0 0 0 0 1 0 1 0 1 0 0 } { appearance { +edge } LIST { < "file1" } { : fred } } VECT 1 2 0 2 0 0 0 0 1 1 2 is a valid OOGL object. The last example is only valid when it is delimited unambiguously by residing in its own disk file. The "<" construct causes a disk file to be read. Note that this isn't a general textual "include" mechanism; a complete OOGL object must appear in the referenced file. Files read using "<" are sought first in the directory of the file which referred to them, if any; failing that, the normal search path (set by Geomview's `load-path' command) is used. The default search looks first in the current directory, then in the Geomview data directories. The ":" construct allows references to symbols, created with `define'. A symbol's initial value is a null object. When a symbol is (re)defined, all references to it are automatically changed; this is a crucial part of the support for interprocess communication. Some future version of the documentation should explain this better... Again, white space and line breaks are insignificant, and "#" comments may appear anywhere. File: geomview Node: Appearances, Prev: References, Up: Conventions, Next: Object File Formats Appearances ----------- Geometric objects can have associated "appearance" information, specifying shading, lighting, color, wireframe vs. shaded-surface display, and so on. Appearances are inherited through object hierarchies, e.g. attaching an appearance to a `LIST' means that the appearance is applied to all the `LIST''s members. Some appearance-related properties are relegated to "material" and "lighting" substructures. Take care to note which properties belong to which structure. Here's an example appearance structure including values for all attributes. Order of attributes is unimportant. As usual, white space is irrelevant. Boolean attributes may be preceded by "+" or "-" to turn them on or off; "+" is assumed if only the attribute name appears. Other attributes expect values. A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2", selects "override" status for that attribute. appearance { +face # draw faces of polygons -edge # don't draw edges of polygons -transparent # don't attempt transparency (not implemented) +normal # do draw surface-normal vectors normscale .25 # ... with length .25 in object coordinates +evert # do evert polygon normals where needed so as # to always face the camera shading smooth # or "shading constant" or "shading flat". # smooth = Gouraud shading; flat = faceted. linewidth 3 # lines & edges are 3 pixels wide. material { # Here's a material definition; # it could also be read from a file as in # "material < file.mat" ka 1.0 # ambient reflection coefficient. ambient .3 .5 .3 # ambient color (red, green, blue components) # The ambient contribution to the shading is # the product of ka, the ambient color, # and the color of the ambient light. kd 0.8 # diffuse-reflection coefficient. diffuse .9 1 .4 # diffuse color. # (In "shading constant" mode, the surface # is colored with the diffuse color.) ks 1.0 # specular reflection coefficient. specular 1 1 1 # specular (highlight) color. shininess 25 # specular exponent; larger values give # sharper highlights. alpha 1.0 # opacity; 0 = transparent (invisible) # when transparency is enabled. edgecolor 1 1 0 # line & edge color normalcolor 0 0 0 # color for surface-normal vectors } lighting { # Lighting model ambient .3 .3 .3 # ambient light replacelights # "Use only the following lights to # illuminate the objects under this # appearance." # Without "replacelights", any lights # are added to those already in the scene. # Now a collection of real lights light { color 1 .7 .6 # light color position 1 0 .5 0 # light position [distant light] # given in homogeneous coordinates. # With fourth component = 0, # this means a light coming from # direction (1,0,.5). } light { # Another light. color 1 1 1 position 0 0 .5 1 # light at finite position ... location camera # specified in camera coordinates. # (Since the camera looks toward -Z, # this example places the light # .5 unit behind the eye.) # Possible "location" keywords: # global light position is in world coordinates # This is the default if no location specified. # camera position is in the camera's coordinate system # local position is in the coordinate system where # the appearance was defined } } # end lighting model } # end appearance There are rules for inheritance of appearance attributes when several are imposed at different levels in the hierarchy. For example, Geomview installs a backstop appearance which provides default values for most parameters; its control panels install other appearances which supply new values for a few attributes; user-supplied geometry may also contain appearances. The general rule is that the child's appearance (the one closest to the geometric primitives) wins. So setting an appearance attribute in an object's definition will prevent the viewer controls from affecting that object's display. File: geomview Node: Object File Formats, Prev: Appearances, Up: OOGL File Formats, Next: QUAD Object File Formats =================== * Menu: * QUAD:: List of quadrilaterals. * MESH:: Rectangularly-connected mesh. * BBP and BEZ:: List of Bezier surface patches. * OFF:: Polyhedra: polygons with shared vertices. * VECT:: List of points and lines. * INST:: Transformed Instance of another object. * LIST:: List of other objects. * TLIST:: Collection of 4x4 transformation matrices. * GROUP:: Obsolete format for collections of objects. * DISCGRP:: Discrete Group objects. File: geomview Node: QUAD, Prev: Object File Formats, Up: Object File Formats, Next: MESH `QUAD': collection of quadrilaterals ------------------------------------ The conventional suffix for a `QUAD' file is `.quad'. The file syntax is [C][N][4]QUAD -or- [C][N][4]POLY # Key word VERTEX VERTEX VERTEX VERTEX # 4*N vertices for some N VERTEX VERTEX VERTEX VERTEX ... The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY', where the optional `C' and `N' prefixes indicate that each vertex includes colors and normals respectively. That is, these files begin with one of the words `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY' `CPOLY' `NPOLY' `CNPOLY' (but not `NCQUAD' or `NCPOLY'). `QUAD' and `POLY' are synonymous; both forms are allowed just for compatibility with ChapReyes. Following the key word is an arbitrary number of groups of four vertices, each group describing a quadrilateral. See the Vertex syntax above. The object ends at end-of-file, or with a closebrace if incorporated into an object reference (see above). A `QUAD BINARY' file format is accepted; *Note Binary format::. The first word of binary data must be a 32-bit integer giving the number of quads in the object; following that is a series of 32-bit floats, arranged just as in the ASCII format. File: geomview Node: MESH, Prev: QUAD, Up: Object File Formats, Next: BBP and BEZ `MESH': rectangularly-connected mesh ------------------------------------ The conventional suffix for a `MESH' file is `.mesh'. The file syntax is [C][N][Z][4][U][u][v]MESH # Key word NU NV # Mesh dimensions # NU*NV vertices, in format specified # by initial key word VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU-1,0) VERTEX(0,1) ... VERTEX(NU-1,1) ... VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1) The key word is `[C][N][Z][4][U][u][v]MESH'. The optional prefix characters mean: `C' Each vertex (see Vertices above) includes a 4-component color. `N' Each vertex includes a surface normal vector. `Z' Of the 3 vertex position values, only the Z component is present; X and Y are omitted, and assumed to equal the mesh (u,v) coordinate so X ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where Nu and Nv are the mesh dimensions -- see below. `4' Vertices are 4D, each consists of 4 floating values. `Z' and `4' cannot both be present. `U' Each vertex includes a 3-component texture space parameter. This is not yet implemented and should not be used. `u' The mesh is wrapped in the u-direction, so the (0,v)'th vertex is connected to the (NU-1,v)'th for all v. `v' The mesh is wrapped in the v-direction, so the (u,0)'th vertex is connected to the (u,NV-1)'th for all u. Thus a u-wrapped or v-wrapped mesh is topologically a cylinder, while a uv-wrapped mesh is a torus. Note that the order of prefix characters is significant; a colored, u-wrapped mesh is a `CuMESH' not a `uCMESH'. Following the mesh header are integers NU and NV, the dimensions of the mesh. Then follow NU*NV vertices, each in the form given by the header. They appear in v-major order, i.e. if we name each vertex by (u,v) then the vertices appear in the order (0,0) (1,0) (2,0) (3,0) ... (NU-1,0) (0,1) (1,1) (2,1) (3,1) ... (NU-1,1) ... (0,Nv-1) ... (NU-1,NV-1) A `MESH BINARY' format is accepted; *Note Binary format::. The values of NU and NV are 32-bit integers; all other values are 32-bit floats. File: geomview Node: BBP and BEZ, Prev: MESH, Up: Object File Formats, Next: OFF Bezier Surfaces --------------- The conventional file suffixes for Bezier surface files are `.bbp' or `.bez'. A file with either suffix may contain either type of patch. Syntax: [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST] # NU, NV are u- and v-direction # polynomial degrees in range 1..6 # ND = dimension: 3->3-D, 4->4-D (rational) # (The '<' and '>' do not appear in the input.) # NU,NV,ND are each a single decimal digit. # BBP form implies NU=NV=ND=3 so BBP = BEZ333. # Any number of patches follow the header # (NU+1)*(NV+1) patch control points # each 3 or 4 floats according to header VERTEX(u=0,v=0) VERTEX(1,0) ... VERTEX(NU,0) VERTEX(0,1) ... VERTEX(NU,1) ... VERTEX(0,NV) ... VERTEX(NU,NV) # ST texture coordinates if mentioned in header `S'(u=0,v=0) `T'(0,0) `S'(0,NV) `T'(0,NV) `S'(NU,0) `T'(NU,0) `S'(NU,NV) `T'(NU,NV) # 4-component float (0..1) R G B A colors # for each patch corner if mentioned in header `RGBA'(0,0) `RGBA'(0,NV) `RGBA'(NU,0) `RGBA'(NU,NV) These formats represent collections of Bezier surface patches, of degrees up to 6, and with 3-D or 4-D (rational) vertices. The header keyword has the forms `[ST]BBP' or `[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are not part of the keyword. The `ST' prefix on `BBP', or `_ST' suffix on `BEZuvn', indicates that each patch includes four pairs of floating-point texture-space coordinates, one for each corner of the patch. The `C' prefix on `BEZuvn' indicates a colored patch, including four sets of four-component floating-point colors (red, green, blue, and alpha) in the range 0..1, one color for each corner. NU and NV, each a single digit in the range 1..6, are the patch's polynomial degree in the u and v direction respectively. ND is the number of components in each patch vertex, and must be either `3' for 3-D or `4' for homogeneous coordinates, that is, rational patches. `BBP' patches are bicubic patches with 3-D vertices, so `BBP' = `BEZ333' and `STBBP' = `BEZ333_ST'. Any number of patches follow the header. Each patch comprises a series of patch vertices, followed by optional (s,t) texture coordinates, followed by optional (r,g,b,a) colors. Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we designate a vertex by its control point indices (u,v) the order is (0,0) (1,0) (2,0) ... (NU,0) (0,1) (1,1) (2,1) ... (NU,1) ... (0,NV) ... (NU,NV) with each vertex containing either 3 or 4 floating-point numbers as specified by the header. If the header calls for ST coordinates, four pairs of floating-point numbers follow: the texture-space coordinates for the (0,0), (NU,0), (0,NV), and (NU,NV) corners of the patch, respectively. If the header calls for colors, four four-component (red, green, blue, alpha) floating-point colors follow, one for each patch corner. The series of patches ends at end-of-file, or with a closebrace if incorporated in an object reference. File: geomview Node: OFF, Prev: BBP and BEZ, Up: Object File Formats, Next: VECT OFF Files --------- The conventional suffix for `OFF' files is `.off'. Syntax: [C][N][4]OFF # Header keyword (optional) NVERTICES NFACES NEDGES # NEdges not used or checked X[0] Y[0] Z[0] # Vertices, possibly with colors # and/or normals if `COFF' or `NOFF' ... X[NVERTICES-1] Y[NVERTICES-1] Z[NVERTICES-1] # Faces # NV = # vertices on this face # V[0] ... V[NV-1]: vertex indices # in range 0..NVERTICES-1 NV V[0] V[1] ... V[NV-1] COLORSPEC ... # COLORSPEC continues past V[NV-1] # to end-of-line; may be 0 to 4 numbers # nothing: default # integer: colormap index # 3 or 4 integers: RGB[A] values 0..255 # 3 or 4 floats: RGB[A] values 0..1 `OFF' files (name for "object file format") represent collections of planar polygons with possibly shared vertices, a convenient way to describe polyhedra. The polygons may be concave but there's no provision for polygons containing holes. An `OFF' file may begin with the keyword `OFF'; it's recommended but optional, as many existing files lack this keyword. Three ASCII integers follow: NVERTICES, NFACES, and NEDGES. Thse are the number of vertices, faces, and edges, respectively. Current software does not use nor check NEDGES; it needn't be correct but must be present. The vertex coordinates follow: dimension * NVERTICES floating-point values. They're implicitly numbered 0 through NVERTICES-1. dimension is either 3 (default) or 4 (specified by the key character `4' directly before `OFF' in the keyword). Following these are the face descriptions, typically written with one line per face. Each has the form N VERT1 VERT2 ... VERTN [COLOR] Here N is the number of vertices on this face, and VERT1 through VERTN are indices into the list of vertices (in the range 0..NVERTICES-1). The optional COLOR may take several forms. Line breaks are significant here: the COLOR description begins after VERTN and ends with the end of the line (or the next # comment). A COLOR may be: nothing the default color one integer index into "the" colormap; see below three or four integers RGB and possibly alpha values in the range 0..255 three or four floating-point numbers RGB and possibly alpha values in the range 0..1 For the one-integer case, the colormap is currently read from the file `cmap.fmap' in Geomview's `data' directory. Some better mechanism for supplying a colormap is likely someday. The meaning of "default color" varies. If no face of the object has a color, all inherit the environment's default material color. If some but not all faces have colors, the default is gray (R,G,B,A=.666). A `[C][N]OFF BINARY' format is accepted; *Note Binary format::. It resembles the ASCII format in almost the way you'd expect, with 32-bit integers for all counters and vertex indices and 32-bit floats for vertex positions (and vertex colors or normals if `COFF'/`NOFF'/`CNOFF' format). Exception: each face's vertex indices are followed by an integer indicating how many color components accompany it. Face color components must be floats, not integer values. Thus a colorless triangular face might be represented as int int int int int 3 17 5 9 0 while the same face colored red might be int int int int int float float float float 3 17 5 9 4 1.0 0.0 0.0 1.0 File: geomview Node: VECT, Prev: OFF, Up: Object File Formats, Next: INST VECT Files ---------- The conventional suffix for `VECT' files is `{.vect}.' Syntax: [4]VECT NPOLYLINES NVERTICES NCOLORS NV[0] ... NV[NPOLYLINES-1] # number of vertices # in each polyline NC[0] ... NC[NPOLYLINES-1] # number of colors supplied # in each polyline VERT[0] ... VERT[NVERTICES-1] # All the vertices # (3*NVertices floats) COLOR[0] ... COLOR[NCOLORS-1] # All the colors # (4*NColors floats, RGBA) `VECT' objects represent lists of polylines (strings of connected line segments, possibly closed). A degenerate polyline can be used to represent a point. A `VECT' file begins with the key word `VECT' or `4VECT' and three integers: NLINES, NVERTICES, and NCOLORS. Here NLINES is the number of polylines in the file, NVERTICES the total number of vertices, and NCOLORS the number of colors as explained below. Next come NLINES integers NV[0] NV[1] NV[2] ... NV[NLINES-1] giving the number of vertices in each polyline. A negative number indicates a closed polyline; 1 denotes a single-pixel point. The sum (of absolute values) of the NV[I] must equal NVERTICES. Next come NLINES more integers Nc[i]: the number of colors in each polyline. Normally one of three values: 0 No color is specified for this polyline. It's drawn in the same color as the previous polyline. 1 A single color is specified. The entire polyline is drawn in that color. abs(NV[I]) Each vertex has a color. Either each segment is drawn in the corresponding color, or the colors are smoothly interpolated along the line segments, depending on the implementation. The sum of the NC[I] must equal NCOLORS. Next come NVERTICES groups of 3 or 4 floating-point numbers: the coordinates of all the vertices. If the keyword is 4VECT then there are 4 values per vertex. The first abs(NV[0]) of them form the first polyline, the next abs(NV[1]) form the second and so on. Finally NCOLORS groups of 4 floating-point numbers give red, green, blue and alpha (opacity) values. The first NC[0] of them apply to the first polyline, and so on. A VECT BINARY format is accepted; *Note Binary format::. The binary format exactly follows the ASCII format, with 32-bit ints where integers appear, and 32-bit floats where real values appear. File: geomview Node: INST, Prev: VECT, Up: Object File Formats, Next: INST Examples INST Files ---------- The conventional suffix for a `INST' file is `.inst'. An `INST' applies a 4x4 transformation to another OOGL object. It begins with `INST' followed by these sections which may appear in any order: geom OOGL-OBJECT specifies the OOGL object to be instantiated. *Note References::, for the syntax of an OOGL-OBJECT. The keyword `unit' is a synonym for `geom'. transform ["{"] `4x4 transform' ["}"] specifies a single transformation matrix. Either the matrix may appear literally as 16 numbers, or there may be a reference to a "transform" object, i.e. "<" file-containing-4x4-matrix or ":" symbol-representing-"transform"-object> Another way to specify the transformation is transforms OOGL-OBJECT The OOGL-OBJECT must be a `TLIST' object (list of transformations) object, or a `LIST' whose members are ultimately `TLIST' objects. In effect, the `transforms' keyword takes a collection of 4x4 matrices and replicates the `geom' object, making one copy for each 4x4 matrix. If no `transform' nor `transforms' keyword appears, no transformation is applied (actually the identity is applied). This might be useful, e.g., for wrapping an appearance around an externally-supplied object. *Note Transformation matrices::, for the matrix format. There is no INST BINARY format. * Menu: * INST Examples:: Some example of `INST' Files. File: geomview Node: INST Examples, Prev: INST, Up: Object File Formats, Next: LIST INST Examples ............. Here are some examples of `INST' files INST unit < xyz.vect transform { 1 0 0 0 0 1 0 0 0 0 1 0 1 3 0 1 } { appearance { +edge material { edgecolor 1 1 0 } } INST geom < mysurface.quad } {INST transform {: T} geom {<dodec.off}} { INST transforms { LIST { < some-matrices.prj } { < others.prj } { TLIST <still more of them> } } geom { # stuff replicated by all the above matrices ... } } File: geomview Node: LIST, Prev: INST Examples, Up: Object File Formats, Next: TLIST LIST Files ---------- The conventional suffix for a `LIST' file is `.list'. A list of OOGL objects Syntax: LIST OOGL-OBJECT OOGL-OBJECT ... Note that there's no explicit separation between the oogl-objects, so they should be enclosed in curly braces ({ }) for sanity. Likewise there's no explicit marker for the end of the list; unless appearing alone in a disk file, the whole construct should also be wrapped in braces, as in: { LIST { QUAD ... } { < xyz.quad } } A `LIST' with no elements, i.e. `{ LIST }', is valid, and is the easiest way to create an empty object. For example, to remove a symbol's definition you might write { define somesymbol { LIST } } File: geomview Node: TLIST, Prev: LIST, Up: Object File Formats, Next: GROUP TLIST Files ----------- The conventional suffix for a `TLIST' file is `.grp' ("group") or or `.prj' ("projective" matrices). Collection of 4x4 matrices, used in the `transforms' section of and `INST' object. Syntax: TLIST # key word <4x4 matrix (16 floats)> ... # Any number of 4x4 matrices `TLIST's are used only within the `transforms' clause of an `INST' object. They cause the `INST's `geom' object to be instantiated once under each of the transforms in the `TLIST'. The effect is like that of a `LIST' of `INST's each with a single transform, and all referring to the same object, but is more efficient. Be aware that a `TLIST' is a kind of geometry object, distinct from a `transform' object. Some contexts expect one type of object, some the other. For example in INST transform { : MYT } geom { ... } MYT must be a transform object, which might have been created with the gcl (read transform { define myT 1 0 0 1 ... }) while in INST transforms { : MYTS } geom { ... } or INST transforms { LIST {: MYTS} {< more.prj} } geom { ... } MYTS must be a geometry object, defined e.g. with (read geometry { define MYTS { TLIST 1 0 0 1 ... } }) A `TLIST BINARY' format is accepted. Binary data begins with a 32-bit integer giving the number of transformations, followed by that number of 4x4 matrices in 32-bit floating-point format. The order of matrix elements is the same as in the ASCII format.